<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
	
  <meta http-equiv="CONTENT-TYPE"
 content="text/html; charset=iso-8859-1">
  <title>Dataxi-intro</title>
	 	
  <meta name="GENERATOR" content="OpenOffice.org 1.0.2  (Linux)">
	
  <meta name="CREATED" content="20030710;18203500">
	
  <meta name="CHANGED" content="20030711;9063200">
	
  <style>
	<!--
		H6.western { font-family: "Albany", sans-serif; font-size: 10pt }
		H6.cjk { font-size: 10pt }
		H6.ctl { font-size: 10pt }
		H3.western { font-family: "Albany", sans-serif }
		DD.western { so-language: en-GB }
		P.sdendnote { margin-left: 0.5cm; text-indent: -0.5cm; margin-bottom: 0cm; font-size: 10pt }
		A.sdendnoteanc { font-size: 57% }
	-->
	</style>
</head>
<body>
<h1 style="text-align: center;">Dataxi introduction</h1>
<div style="text-align: center;">
<address>by Jyry Kuukkanen</address>
</div>
<p>This document describes the general idea behind Dataxi. It tries to
shed some light to the inner works behind the scenes. After reading
this, it should be clear what Dataxi is, what one can do with it, and
what one can not do with it.</p>
<h3 class="western">1 Key features</h3>
<ul>
  <li> One-form-does-all approach to query, browse and modify tables in
database 	 Forms 	can handle two or more levels of table relations 	 Any
	visual HTML editor may be used to build a Dataxi form 	</li>
</ul>
<ul>
  <li> 100% 	database independent (once system tables are created - auto
build 	might fail on some databases) 	</li>
</ul>
<ul>
  <li> No 	programming skills required for building a (simple) system
with 	Dataxi 	</li>
</ul>
<ul>
  <li> Developers 	may call own scripts forms and menus to provide
custom functionality 		</li>
</ul>
<ul>
  <li> Server 	(and client) side printing available through dzDocPrint
(produces 	PDF) 2 In short 	</li>
</ul>
<p>Dataxi is a middle-ware application for the Web, that handles user
defined forms that interacts with the database for querying, browsing
and editing. The forms are defined in HTML format and thus may be
created by a visual HTML editor very quickly.</p>
<p>Because of the web-browser interface, Dataxi uses a state machine
for improved security and to prevent the user from stepping back and
forth using browser's page history. Even though Dataxi cannot prevent
user from pressing the back button, it can detect it and force the user
to login again to restore the last sane state.</p>
<p>Dataxi is not suitable for anonymous, public usage as-is. However,
it does offer an API (application programming interface) for any self
made public Web-interface, like it does for it's own forms. This way a
developer can benefit from the Dataxi Kone, the database interface, that
isolates the user interface system from the actual database.</p>
<p>A system build using Dataxi is based around forms that are used for
querying, browsing and editing. That alone would not be very useful and
hence Dataxi provides methods to implement actual actions to process the
data. The actions are simply PHP scripts that are triggered from Dataxi
menu, sub-menu of any form, or from a event such as post field trigger
of a field on a form.</p>
<p>As mentioned before, Dataxi is not for a public web-browser
interface. A shopping cart application is out of the question using
Dataxi forms. However, it is important to understand that Dataxi is
perfect for the intranet side of such application, when there is a need
to query, browse or edit either rudimentary tables or the actual
shopping events and orders.</p>
<p>Last but not least, one important component in Dataxi is a document
printer that produces PDF output for printer or file. The dzDocPrint
component is not for reporting, really, but for formal printouts that
needs very accurate placing, such as an invoice or sales order.</p>
<h3 class="western">3 Data structures</h3>
<p style="margin-bottom: 0cm;">It is not rare that a set of data viewed
on a form is spread over several tables in database.</p>
<p style="margin-bottom: 0cm;">A form designed for updating a
CD-collection would require two tables: the main table for album title,
author, genre etc., and the other for track details. These two tables
have a relationship master - detail, where one row in the master table
matches one or more rows in details table. The details table's key
structure would then be albumno + trackno.</p>
<p style="margin-bottom: 0cm;">Dataxi transfers data internally, from
and to the Kone, as columns and as columns only. Some columns may have
more than one row, though. An album data set would consist of several
columns, like title, author, as well as track name and track duration.
Those column belonging to the master table would have only one value,
row, but the track columns each would have as many rows as there are
tracks in the album.</p>
<p style="margin-bottom: 0cm;">When passing this set of data inside the
system, Dataxi does not know nor care how these columns relate to each
other. The data structure is kept separately from the actual data.</p>
<p style="margin-bottom: 0cm;">When describing a data structure, the
only thing required is a list of tables involved with the structure, how
they relate to each other and each table's key structure.</p>
<p style="margin-bottom: 0cm;">The structure may be specified in the
form's HTML source file or in a separate text file that is referred to
from the form, or any PHP script using Kone.</p>
<p style="margin-bottom: 0cm;">Below is a simple example, that
describes two table, how they relate to each other, and what are their
key columns.</p>
<pre><dd lang="en-GB" class="western">albums={ key=albumno:int:$auto }</dd><dd
 lang="en-GB" class="western" style="margin-bottom: 0.5cm;">tracks={ key=$albums,trackno:int:$auto }</dd></pre>
<p style="margin-bottom: 0cm;"> A system tag "$auto" is found in both
table descriptions and it simply means that the column in question is
automatically numbered. This tag may only be used with datatype integer
for now.</p>
<p style="margin-bottom: 0cm;">The "tracks" table uses another system
tag that refers to the "albums" table. The idea is, that "tracks" will
get exactly same key structure as "albums", plus an extra column,
trackno. Even more important meaning using table tag is to establish the
relationship between these two table.</p>
<p style="margin-bottom: 0cm;">The first table listed is always the
master table. Master table may also have parallel tables, with the very
same key structure, but the first table listed is the very master of all
other tables, and all other table must relate to it or it's subtables.</p>
<p style="margin-bottom: 0cm;">In some cases the sub-table's key
columns does not quite match that of the master table, a list of name
convention is introduced: $albums:mastername/localname;master2/local2.
Please see Dataxi-forms-howto for full details of the structure
description.</p>
<p style="margin-bottom: 0cm;">Ones the structure is described, columns
are referred by "table.column" notation and the system is automatically
aware how to treat them.</p>
<h3 class="western">4 Forms</h3>
<p style="margin-bottom: 0cm;">As mentioned earlier, Dataxi system is
very form centric when it comes to the client side interface.</p>
<p style="margin-bottom: 0cm;">Then the user logs in to the system, he
is presented a view that is divided into three frames. At the top is the
main menu bar. The bottom frame acts as a status and navigator bar for
current form. The middle frame is the actual work space where the form
is opened from the menu.</p>
<p style="margin-bottom: 0cm;">Once the form is selected from the menu,
it opens to the work space. The initial mode is query.</p>
<p style="margin-bottom: 0cm;">As the same form may be used for
querying, browsing and editing, the form has as many modes it operates
in. The current mode is displayed in the navigator bar.</p>
<p style="margin-bottom: 0cm;">Depending on the mode, the navigator bar
offers different selection of actions. In q"Query" mode, the user may
only accept the query, close the form or enter to the "New" mode.</p>
<p style="margin-bottom: 0cm;">The "New" mode is a special case of
"Edit" and is used for entering new data. The "New" mode can be entered
from both "Query" and "Browse" mode.</p>
<h3 class="western">4.1 Query mode</h3>
<p style="margin-bottom: 0cm;">The initial state when a form is opened
from the menu.</p>
<p style="margin-bottom: 0cm;">In this mode the user may enter query
conditions to the column. Accepting the query conditions without setting
any of them, causes the system to select all rows in the table(s) to be
browsed.</p>
<p style="margin-bottom: 0cm;">The query conditions may include
"greater than", "less than"and such notations. "&gt;31.12.2002" in a
date column would cause the query to limit the results for rows that are
dated after 31st of December, 2003.Below is the complete list of
available operators and their description.</p>
<center> 	
<table width="50%" border="1" cellpadding="4" cellspacing="3">
		<col width="85*"> 		<col width="85*"> 		<col width="85*"> 		<thead> 			<tr
 valign="top">
				<th width="33%"> 					
    <p align="left">Notation</p>
				</th>
				<th width="33%"> 					
    <p align="left">Description</p>
				</th>
				<th width="33%"> 					
    <p align="left">Example</p>
				</th>
			</tr>
		</thead> 		<tbody>
			<tr valign="top">
				<td width="33%"> 					
      <p align="left">&gt;</p>
				</td>
				<td width="33%"> 					
      <p align="left">Greater than</p>
				</td>
				<td width="33%"> 					
      <p align="left">&gt;34</p>
				</td>
			</tr>
			<tr valign="top">
				<td width="33%"> 					
      <p align="left">&gt;=</p>
				</td>
				<td width="33%"> 					
      <p align="left">Greater than or equal to</p>
				</td>
				<td width="33%"> 					
      <p align="left">&gt;=31.11.2002</p>
				</td>
			</tr>
			<tr valign="top">
				<td width="33%"> 					
      <p align="left">&lt;</p>
				</td>
				<td width="33%"> 					
      <p align="left">Less than</p>
				</td>
				<td width="33%"> 					
      <p align="left">&lt;foo</p>
				</td>
			</tr>
			<tr valign="top">
				<td width="33%"> 					
      <p align="left">&lt;=</p>
				</td>
				<td width="33%"> 					
      <p align="left">Less than or equal to</p>
				</td>
				<td width="33%"> 					
      <p align="left">&lt;=11:30:00</p>
				</td>
			</tr>
			<tr valign="top">
				<td width="33%"> 					
      <p align="left"><br>
					</p>
				</td>
				<td width="33%"> 					
      <p align="left">Equal to</p>
				</td>
				<td width="33%"> 					
      <p align="left">foobar</p>
				</td>
			</tr>
			<tr valign="top">
				<td width="33%"> 					
      <p align="left">...</p>
				</td>
				<td width="33%"> 					
      <p align="left">Range</p>
				</td>
				<td width="33%"> 					
      <p align="left">12...999</p>
				</td>
			</tr>
			<tr valign="top">
				<td width="33%"> 					
      <p align="left">*</p>
				</td>
				<td width="33%"> 					
      <p align="left">Wildcard</p>
				</td>
				<td width="33%"> 					
      <p align="left">*foobar*</p>
				</td>
			</tr>
		
  </tbody> 	
</table>
</center>
<p style="margin-bottom: 0cm;">When setting a condition for more than
one column, it is important to realise that they are anded, which means
that each row encountered must match all the condition in order to be
returned in the result set.</p>
<h4>4.2 Browse mode</h4>
<p style="margin-bottom: 0cm;">Is the query succeeds and some rows are
found, the form automatically enters the browse mode and displays the
first set of data found. </p>
<p style="margin-bottom: 0cm;">What the query actually does is that it
returns only browse keys, the key values of each master table row that
matched the conditions. Once the browse keys are returned, the system
does a read request for the first browse key and enters the browse mode.</p>
<p style="margin-bottom: 0cm;">The order in which browse keys are
returned is defined when designing the form.</p>
<p style="margin-bottom: 0cm;">The navigator bar displays the number of
rows found by the query and the current browse key position.</p>
<p style="margin-bottom: 0cm;">The browse mode provides a way to take a
quick look at all the found rows in a list view. The navigator button
"///"switches between form and list view. The columns displayed in the
list view are defined while designing the form.</p>
<p style="margin-bottom: 0cm;">Delete button to delete a data set is
available when in form view in browse mode.</p>
<h4>4.3 Edit/new mode</h4>
<p style="margin-bottom: 0cm;">Edit mode may be entered from browse
mode. Once the desired data set is in form view in browse mode, the edit
button re-reads the set it and enters the edit mode.</p>
<p style="margin-bottom: 0cm;">When entering the edit mode, the set is
first locked and read once more to get the freshest possible state of
the set. The locking fails if the set is locked by some other session
and/or user. The current lock owner is displayed in the navigator bar.</p>
<p style="margin-bottom: 0cm;">Once the edit is complete, pressing
"Commit" from the navigator saves the changes to the database. Only
those rows and column modified in any table involved in the set are
updated in the database.</p>
<p style="margin-bottom: 0cm;">The "New" mode does not differ from
"Edit" except in key column value handling of a set. Data sets with
sequential key are auto numbered and such a key column is left empty.
Sets with manually entered key column value causes an error message
display when saving if such a set already exists in the database.</p>
<h3 class="western">5 Kone</h3>
<h4>5.1 Requests</h4>
<p style="margin-bottom: 0cm;">The other side of the system: the
database interface component called Kone.</p>
<p style="margin-bottom: 0cm;">Kone responds to requests sent by the
client side. The client side may be the Dataxi system itself or any PHP
script the developer has put together.</p>
<p style="margin-bottom: 0cm;">There are few request types that include
read, write and query.</p>
<p style="margin-bottom: 0cm;">The requests consists of two blocks:
control and data.</p>
<p style="margin-bottom: 0cm;">The control block declares the request
type, data structure (it's name or actual description), user id etc.</p>
<p style="margin-bottom: 0cm;">The data block contains the columns
names and possibly values involved with the request.</p>
<p style="margin-bottom: 0cm;">All requests, but the special system and
authentication requests, must provide the structure of the set in
question. The format of the structure is better explained in details in
dataxi-kone-howto.</p>
<h4>5.2 Database updating</h4>
<p style="margin-bottom: 0cm;">Due to the nature of Kone, all SQL
clauses are generated on the fly by Kone. No SQL skills are required by
the developer using Kone as an interface to the database.</p>
<p style="margin-bottom: 0cm;">The write request works both for new or
exising set. The only difference is that new set using a sequence for
key column is set in the process of writing. To ensure that the write
truly updates the database, a read and lock request are first performed
to read old version of the set. This way the developer does not have to
care, whether a set by the same key already exists in the database or
not, because Kone writes it to the database as new or updates the old
one as needed.</p>
<h4>5.3 Row locks</h4>
<p style="margin-bottom: 0cm;">Kone handles row lockings. The locks are
stored in the database lock table and are hence database independent.
The locks table is accessed though system menu like any other table or
set. This enables deleting rows locks manually by the administrator when
such a need arises.</p>
<h4>5.4 Sequences</h4>
<p style="margin-bottom: 0cm;">Kone also handles auto numbering of rows
for any column on any table.</p>
<p style="margin-bottom: 0cm;">The sequences may be for one or more
columns. The most often used case is where there is a table with one key
column that is automatically numbered: 1, 2, 3 etc. There are, however,
many occasions when this is far from adequate.</p>
<p style="margin-bottom: 0cm;">When table key consists of series and
sequence, the next number in the sequence depends on the value of
series. For example, sales orders might be numbered so that each year
starts the sequence from 1, the series would be the year. Kone handles
these multi column sequences automatically. Once the series is set /a
year specified), Kone takes care and finds the next value in the
sequence for it.</p>
<p style="margin-bottom: 0cm;">Because Kone sequence handling works
independently from the database engine, sequences can be set to any
column or columns on a table. This enables some interesting
possibilities, like double sequencing.</p>
<p style="margin-bottom: 0cm;">Double sequencing is very practical when
master database is not accessible all the time. The application may be
run more locally and synchronised with the master as often as required
or when possible. The tables requiring sequences on them have total of
three column to identify them. The main key consists of two columns:
host and no. Host is the host name the database runs on (or name of the
office etc.) and the no. is the actual sequence column. The third column
required is the official sequence that only gets updated when
synchronised with the master database. This way the table row may be
referred by the office/local host sequence no. or by the official
company/system wide sequence no.</p>
<h3 class="western">6 Custom scripts</h3>
<p style="margin-bottom: 0cm;">Because Dataxi system is not very usable
but for basic query, browse and edit purpose, a scripting language to
enable the developer quickly build the logic for actual data processing,
PHP makes a fine choice. In most cases, however, any scripting language
may be used for that matter.</p>
<p style="margin-bottom: 0cm;">To take the full benefit of Kone API
without having to write the interface classes in the language of
preference, using PHP makes more sense. In the next major release of
Dataxi, the interface is to be changed to use XML so this annoyance
should go away.</p>
<h3 class="western">7 History</h3>
<p style="margin-bottom: 0cm;">There are reasons Dataxi was written and
developed to be what it is today.</p>
<p style="margin-bottom: 0cm;">Anyone who has been using Advanced
Revelation (Arev) or Pick<a class="sdendnoteanc" name="sdendnote1anc"
 href="#sdendnote1sym"><sup>i</sup></a> should find Dataxi very familiar.</p>
<p style="margin-bottom: 0cm;">Arev enabled rapid system development so
the developer could focus on the logic itself rather than spending time
in the most time consuming tasks such as user-interface and data
validation.</p>
<p style="margin-bottom: 0cm;">Arev introduced the one-form-does-all
method and it is still a mystery to me why that approach is not used by
any other tool or system. I know by experience users like it very much
because there is less to learn - the same familiar form they use for
entering invoices is used to search and browse them.</p>
<p style="margin-bottom: 0cm;"><br>
</p>
<p style="margin-bottom: 0cm;">Arev has it's limitations and the more
time passes the more limitations are encountered:</p>
<p style="margin-bottom: 0cm;"><br>
</p>
<ul>
	<li><dd lang="en-GB" class="western" style="margin-bottom: 0.5cm;">DOS
	based application. Microsoft has done all it can so that DOS
	applications run poorer and poorer by every release of it's 	operating
systems.</dd>
  </li>
</ul>
<ul>
	<li><dd lang="en-GB" class="western" style="margin-bottom: 0.5cm;">Native
	proprietary flat-file format. None or not proper support for 	external
databases.</dd>
  </li>
</ul>
<ul>
	<li><dd lang="en-GB" class="western" style="margin-bottom: 0.5cm;">Not
	truly relational database. Far from it actually. Two levels are 	fine,
more is practically impossible. This makes reporting pretty 	tricky with
anything more complex.</dd>
  </li>
</ul>
<ul>
	<li><dd lang="en-GB" class="western" style="margin-bottom: 0.5cm;">Sequence
	numbering is inadequate: next number in sequence is picked when
	entering new data starts, not when committing. This causes temporary
	gaps in the sequence that may be critical in many occasions.</dd>
  </li>
</ul>
<ul>
	<li><dd lang="en-GB" class="western" style="margin-bottom: 0.5cm;">Own
	proprietary scripting language - yet another thing to learn for a 	new
developer. 	</dd>
  </li>
</ul>
<p style="margin-bottom: 0cm;">Dataxi was developed keeping Arev in
mind in good and in bad. Good features were inherited and bad cast away
as far as possible.</p>
<p style="margin-bottom: 0cm;">First write of Dataxi was started using
Delphi<a class="sdendnoteanc" name="sdendnote2anc" href="#sdendnote2sym"><sup>ii</sup></a>
for WinXX environment. That would have lead to another lock-in:
proprietary tool and OS. Web interface made more than sense even though
java application is not very bad choice either. In the end PHP was
picked as it suited the job best with less hassle. PHP offers low
learning curve for a developer with more or less programming skills.</p>
<p style="margin-bottom: 0cm;">Ah, one more thing, mainly for those who
are still using Arev and are looking for an alternatice. Because of the
Arev background, I have written an importer from Arev to Dataxi system.
It even enables Arev and Dataxi to be used side to side, so that Arev
acts as the master and Dataxi as slave. Any data entered through Arev
appears on the Dataxi side after some delay.</p>
<h3 class="western">8 Links</h3>
<ul>
	<li>Apache http://www.apache.org </li>
</ul>
<ul>
	<li>Dataxi 	http://dataxi.sourceforge.net </li>
</ul>
<ul>
	<li>Pdflib http://www.pdflib.net </li>
</ul>
<ul>
	<li>Php http://www.php.net/ </li>
</ul>
<ul>
	<li>PostgreSQL 	http://www.postgresql.org </li>
</ul>
<ul>
	<li>Webmin http://www.webmin.com </li>
</ul>
<div id="sdendnote1"> 	
<p class="sdendnote"><a class="sdendnotesym" name="sdendnote1sym"
 href="#sdendnote1anc">i</a>Advanced 	Revelation and Pick are
registered trademarks of Revelation 	Technologies</p>
</div>
<div id="sdendnote2"> 	
<p class="sdendnote"><a class="sdendnotesym" name="sdendnote2sym"
 href="#sdendnote2anc">ii</a>Delphi 	is a trademark of Borland</p>
</div>
</body>
</html>
